From d953125970fad2782411e427265a63e40eda3ccf Mon Sep 17 00:00:00 2001 From: Matthias Clasen Date: Tue, 3 Jul 2007 15:38:53 +0000 Subject: [PATCH] Improvements svn path=/trunk/; revision=18352 --- docs/reference/ChangeLog | 6 +++++ docs/reference/gtk/tmpl/gtkbuilder.sgml | 31 ++++++++++++++++--------- 2 files changed, 26 insertions(+), 11 deletions(-) diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog index a71b582133..2d733b2222 100644 --- a/docs/reference/ChangeLog +++ b/docs/reference/ChangeLog @@ -1,3 +1,9 @@ +2007-07-03 Matthias Clasen + + * gtk/tmpl/gtkbuilder.sgml: Some wordsmithing + on the memory management explanation, asked for + by Murray Cumming. + 2007-07-02 Matthias Clasen * === Released 2.11.5 === diff --git a/docs/reference/gtk/tmpl/gtkbuilder.sgml b/docs/reference/gtk/tmpl/gtkbuilder.sgml index 471fd6eeb7..d7b58790e8 100644 --- a/docs/reference/gtk/tmpl/gtkbuilder.sgml +++ b/docs/reference/gtk/tmpl/gtkbuilder.sgml @@ -11,20 +11,29 @@ of a user interface and instantiates the described objects. To pass a description to a GtkBuilder, call gtk_builder_add_from_file() or gtk_builder_add_from_string(). These functions can be called multiple times; the builder merges the content of all descriptions. -The functions gtk_builder_get_object() and gtk_builder_get_objects() -can be used to access the widgets in the interface by the names assigned -to them inside the UI description. The function gtk_builder_connect_signals() -and variants thereof can be used to connect handlers to the named signals -in the description. A GtkBuilder holds a reference to all objects that it has constructed -and drops these references when it is finalized. To keep objects beyond -the lifespan of the builder, they must be fetched with gtk_builder_get_object() -and reffed with g_object_ref(). It is the responsibility of the user -to destroy all toplevel windows that have been constructed by a builder -(these are not automatically cleaned up when the builder is finalized, -since GTK+ itself holds a reference to each toplevel window). +and drops these references when it is finalized. This finalization can +cause the destruction of non-widget objects or widgets which are not +contained in a toplevel window. For toplevel windows constructed by a +builder, it is the responsibility of the user to call gtk_widget_destroy() +to get rid of them and all the widgets they contain. + + +The functions gtk_builder_get_object() and gtk_builder_get_objects() +can be used to access the widgets in the interface by the names assigned +to them inside the UI description. Toplevel windows returned by these +functions will stay around until the user explicitly destroys them +with gtk_widget_destroy(). Other widgets will either be part of a +larger hierarchy constructed by the builder (in which case you should +not have to worry about their lifecycle), or without a parent, in which +case they have to be added to some container to make use of them. +Non-widget objects need to be reffed with g_object_ref() to keep them +beyond the lifespan of the builder. + +The function gtk_builder_connect_signals() and variants thereof can be +used to connect handlers to the named signals in the description. GtkBuilder UI Definitions -- 2.30.2